home *** CD-ROM | disk | FTP | other *** search
gggglllloooobbbb((((3333GGGG)))) gggglllloooobbbb((((3333GGGG)))) NNNNAAAAMMMMEEEE _gggg_llll_oooo_bbbb - generate pathnames matching a pattern SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>> _iiii_nnnn_tttt _gggg_llll_oooo_bbbb_((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_pppp_aaaa_tttt_tttt_eeee_rrrr_nnnn_,,,, _iiii_nnnn_tttt _ffff_llll_aaaa_gggg_ssss_,,,, _iiii_nnnn_tttt_((((_****_eeee_rrrr_rrrr_ffff_uuuu_nnnn_cccc_))))_((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_eeee_pppp_aaaa_tttt_hhhh_,,,, _iiii_nnnn_tttt _eeee_eeee_rrrr_rrrr_nnnn_oooo_))))_,,,, gggglllloooobbbb____tttt ****ppppgggglllloooobbbb))));;;; vvvvooooiiiidddd gggglllloooobbbbffffrrrreeeeeeee((((gggglllloooobbbb____tttt ****ppppgggglllloooobbbb))));;;; DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The structure type gggglllloooobbbb____tttt is defined in the header _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>> and includes at least the following members: MemberType MemberName Description _______________________________________________________________ ssssiiiizzzzeeee____tttt ggggllll____ooooffffffffssss SSSSlllloooottttssss ttttoooo rrrreeeesssseeeerrrrvvvveeee aaaatttt ssssttttaaaarrrrtttt ooooffff ggggllll____ppppaaaatttthhhhvvvv.... cccchhhhaaaarrrr ******** ggggllll____ppppaaaatttthhhhvvvv PPPPooooiiiinnnntttteeeerrrr ttttoooo lllliiiisssstttt ooooffff mmmmaaaattttcccchhhheeeedddd ppppaaaatttthhhhnnnnaaaammmmeeeessss.... ssssiiiizzzzeeee____tttt ggggllll____ppppaaaatttthhhhcccc CCCCoooouuuunnnntttt ooooffff ppppaaaatttthhhhssss mmmmaaaattttcccchhhheeeedddd bbbbyyyy ppppaaaatttttttteeeerrrrnnnn.... The argument _p_a_t_t_e_r_n is a pointer to a pathname pattern to be expanded. The _gggg_llll_oooo_bbbb function matches all accessible pathnames against this pattern and develops a list of all pathnames that match. In order to have access to a pathname, _gggg_llll_oooo_bbbb requires search permission on every component of a path except the last, and read permission on each directory of any filename component of _p_a_t_t_e_r_n that contains any of the following characters: * ? [ The _gggg_llll_oooo_bbbb function stores the number of matched pathnames into ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc and a pointer to a list of pointers to pathnames into ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv.... The pathnames are in sort order as defined by the current setting of the LC_COLLATE category. The first pointer after the last pathname is a null pointer. If the pattern does not match any pathnames, the returned number of matched paths is set to zero, and the contents of ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv are undetermined. It is the caller's responsibility to create the structure pointed to by _gggg_llll_oooo_bbbb. _gggg_llll_oooo_bbbb allocates other space as needed, including the memory pointed to by ggggllll____ppppaaaatttthhhhvvvv.... The _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee function frees any space associated with _gggg_llll_oooo_bbbb from a previous call to _gggg_llll_oooo_bbbb. The _f_l_a_g_s argument is used to control the behaviour of _gggg_llll_oooo_bbbb. The value of _f_l_a_g_s is a bitwise inclusive OR of zero or more of the following constants, which are defined in the header _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>: _G_L_O_B__A_P_P_E_N_D Append pathnames generated to the ones from a previous call to _gggg_llll_oooo_bbbb. PPPPaaaaggggeeee 1111 gggglllloooobbbb((((3333GGGG)))) gggglllloooobbbb((((3333GGGG)))) _G_L_O_B__D_O_O_F_F_S Make use of ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss.... If this flag is set, ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss is used to specify how many null pointers to add to the beginning of ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv.... In other words, ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv will point to ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss null pointers, followed by ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc pathname pointers, followed by a null pointer. _G_L_O_B__E_R_R Causes _gggg_llll_oooo_bbbb to return when it encounters a directory that it cannot open or read. Ordinarily, _gggg_llll_oooo_bbbb continues to find matches. _G_L_O_B__M_A_R_K Each pathname that is a directory that matches _p_a_t_t_e_r_n has a slash appended. _G_L_O_B__N_O_C_H_E_C_K If _p_a_t_t_e_r_n does not match any pathname, then _gggg_llll_oooo_bbbb returns a list consisting of only _p_a_t_t_e_r_n, and the number of matched pathnames is one (1). _G_L_O_B__N_O_E_S_C_A_P_E Disable backslash escaping. _G_L_O_B__N_O_S_O_R_T Ordinarily, _gggg_llll_oooo_bbbb sorts the matching pathnames according to the current setting of the LC_COLLATE category. When this flag is used the order of pathnames returned is unspecified. The GLOB_APPEND flag can be used to append a new set of pathnames to those found in a previous call to _gggg_llll_oooo_bbbb. The following rules apply when two or more calls to _gggg_llll_oooo_bbbb are made with the same value of _p_g_l_o_b and without intervening calls to _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee: The first such call must not set GLOB_APPEND. All subsequent calls must set it. All the calls must set GLOB_DOOFFS, or all must not set it. After the second call, ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv points to a list containing the following: Zero or more null pointers, as specified by GLOB_DOOFFS and ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss.... Pointers to the pathnames that were in the ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv list before the call, in the same order as before. PPPPaaaaggggeeee 2222 gggglllloooobbbb((((3333GGGG)))) gggglllloooobbbb((((3333GGGG)))) Pointers to the new pathnames generated by the second call, in the specified order. The count returned in ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc will be the total number of pathnames from the two calls. The application can change any of the fields after a call to _gggg_llll_oooo_bbbb. If it does, it must reset them to the original value before a subsequent call, using the same _p_g_l_o_b value, to _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee or _gggg_llll_oooo_bbbb with the GLOB_APPEND flag. If, during the search, a directory is encountered that cannot be opened or read and _e_r_r_f_u_n_c is not a null pointer, _gggg_llll_oooo_bbbb calls (*_e_r_r_f_u_n_c()) with two arguments: The _e_p_a_t_h argument is a pointer to the path that failed. The _e_e_r_r_n_o argument is the value of _e_r_r_n_o from that failure, as set by _o_p_e_n_d_i_r(), _r_e_a_d_d_i_r() or _s_t_a_t(). (Other values may be used to report other errors not explicitly documented for those functions.) The following constants are defined as error return values for _gggg_llll_oooo_bbbb: _G_L_O_B__A_B_O_R_T_E_D The scan was stopped because GLOB_ERR was set or (*_e_r_r_f_u_n_c()) returned non-zero. _G_L_O_B__N_O_M_A_T_C_H The pattern does not match any existing pathname, and GLOB_NOCHECK was not set in flags. _G_L_O_B__N_O_S_P_A_C_E An attempt to allocate memory failed. If (*_e_r_r_f_u_n_c()) is called and returns non-zero or if the GLOB_ERR flag is set in _f_l_a_g_s, _gggg_llll_oooo_bbbb stops the scan and returns GLOB_ABORTED after setting _g_l__p_a_t_h_v in _p_g_l_o_b to reflect the paths already scanned. If GLOB_ERR is not set and either _e_r_r_f_u_n_c is a null pointer or (*_e_r_r_f_u_n_c()) returns zero, the error is ignored. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE On successful completion, _gggg_llll_oooo_bbbb returns zero. The argument ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc returns the number of matched pathnames and the argument ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv contains a pointer to a null-terminated list of matched and sorted pathnames. However, if ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc is zero, the contents of ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv is undefined. The _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee function returns no value. PPPPaaaaggggeeee 3333 gggglllloooobbbb((((3333GGGG)))) gggglllloooobbbb((((3333GGGG)))) If _gggg_llll_oooo_bbbb terminates due to an error, it returns one of the non-zero constants defined in _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>. The arguments ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc and ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv are still set as defined above. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS One use of the GLOB_DOOFFS flag is by applications that build an argument list for use with _eeee_xxxx_eeee_cccc_vvvv, _eeee_xxxx_eeee_cccc_vvvv_eeee or _eeee_xxxx_eeee_cccc_vvvv_pppp. Suppose, for example, that an application wants to do the equivalent of: _llll_ssss _----_llll _****_...._cccc But for some reason: _ssss_yyyy_ssss_tttt_eeee_mmmm_((((_""""_llll_ssss _----_llll _****_...._cccc_""""_)))) is not acceptable. The application could obtain approximately the same result using the sequence: gggglllloooobbbbbbbbuuuuffff....ggggllll____ooooffffffffssss ==== 2222;;;; gggglllloooobbbb ((((""""****....cccc"""",,,, GGGGLLLLOOOOBBBB____DDDDOOOOOOOOFFFFFFFFSSSS,,,, NNNNUUUULLLLLLLL,,,, &&&&gggglllloooobbbbbbbbuuuuffff))));;;; gggglllloooobbbbbbbbuuuuffff....ggggllll____ppppaaaatttthhhhvvvv[[[[0000]]]] ====""""llllssss"""";;;; gggglllloooobbbbbbbbuuuuffff....ggggllll____ppppaaaatttthhhhvvvv[[[[1111]]]] ====""""----llll"""";;;; eeeexxxxeeeeccccpppp ((((""""llllssss"""",,,, &&&&gggglllloooobbbbbbbbuuuuffff....ggggllll____ppppaaaatttthhhhvvvv[[[[0000]]]]))));;;; Using the same example: _llll_ssss _----_llll _****_...._cccc _****_...._hhhh could be approximately simulated using GLOB_APPEND as follows: gggglllloooobbbbbbbbuuuuffff....ggggllll____ooooffffffffssss ==== 2222;;;; gggglllloooobbbb ((((""""****....cccc"""",,,, GGGGLLLLOOOOBBBB____DDDDOOOOOOOOFFFFFFFFSSSS,,,, NNNNUUUULLLLLLLL,,,, &&&&gggglllloooobbbbbbbbuuuuffff))));;;; gggglllloooobbbb ((((""""****....hhhh"""",,,, GGGGLLLLOOOOBBBB____DDDDOOOOOOOOFFFFFFFFSSSS||||GGGGLLLLOOOOBBBB____AAAAPPPPPPPPEEEENNNNDDDD,,,, NNNNUUUULLLLLLLL,,,, &&&&gggglllloooobbbbbbbbuuuuffff))));;;; ... AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN UUUUSSSSAAAAGGGGEEEE This function is not provided for the purpose of enabling utilities to perform pathname expansion on their arguments, as the operation is performed by the shell, and utilities are explicitly not expected to redo this. Instead, it is provided for applications that need to do pathname expansion on strings obtained from other sources, such as a pattern typed by a user or read from a file. If a utility needs to see if a pathname matches a given pattern, it can use _ffff_nnnn_mmmm_aaaa_tttt_cccc_hhhh. Note that ggggllll____ppppaaaatttthhhhcccc and ggggllll____ppppaaaatttthhhhvvvv have meaning even if _gggg_llll_oooo_bbbb fails. This allows _gggg_llll_oooo_bbbb to report partial results in the event of an error. However, if ggggllll____ppppaaaatttthhhhcccc is zero, ggggllll____ppppaaaatttthhhhvvvv is unspecified even if _gggg_llll_oooo_bbbb did not return an error. The GLOB_NOCHECK option could be used when an application wants to expand PPPPaaaaggggeeee 4444 gggglllloooobbbb((((3333GGGG)))) gggglllloooobbbb((((3333GGGG)))) a pathname if wildcards are specified, but wants to treat the pattern as just a string otherwise. The _ssss_hhhh utility might use this for option- arguments, for example. The new pathnames generated by a subsequent call with GLOB_APPEND are not sorted together with the previous pathnames. This mirrors the way that the sheel handles pathname expansion when multiple expansions are done on a command line. Applications that need tilde and parameter expansion should use _wwww_oooo_rrrr_dddd_eeee_xxxx_pppp. SSSSEEEEEEEE AAAALLLLSSSSOOOO execv(2), fnmatch(3g), opendir(3b), readdir(3b), stat(2), wordexp(3g), _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>. PPPPaaaaggggeeee 5555 
